What

Adds an idiomatic Ruby convenience layer on top of the existing Options-based API, and decomposes the monolithic README into 14 focused documentation guides.

Why

The SDK's public API felt like a translated TypeScript SDK rather than idiomatic Ruby. This introduces Stripe-inspired ergonomics — module-level config, declarative DSL builders, and simple entry points — while keeping the existing API fully intact and backward compatible.

The 1,600-line README was too large to navigate. Splitting into docs/ makes each topic discoverable and maintainable.

How

Convenience layer (additive, non-breaking)

• Configuration — ClaudeAgent.model = "opus", ClaudeAgent.configure { |c| ... }, Configuration#to_options merges global defaults with per-request overrides
• Entry points — ClaudeAgent.ask(prompt) (one-shot, returns TurnResult) and ClaudeAgent.chat { |c| ... } (multi-turn, auto-cleanup)
• PermissionPolicy — declarative allow/deny/allow_matching/deny_matching DSL compiling to can_use_tool lambda
• HookRegistry — Ruby method names (before_tool_use, on_session_start, etc.) mapping to 22 CLI events, additive merge
• Message module — text_content, session_message?, identifiable?, pattern matching via deconstruct_keys — prepended into all 22 message types and 8 content blocks
• EventHandler.define — block-based DSL for handler definitions
• MCP Server block DSL — Server.new(name:) { |s| s.tool(...) } and symbol type shortcuts (:number, :string, etc.)
• Session resource — Session.retrieve (raises NotFoundError), instance methods rename, tag_session, fork, reload, resume; Session.find switched from full scan to targeted GetSessionInfo lookup
• NotFoundError added to error hierarchy

Documentation

• README trimmed to 120-line primer with install, 6 quick examples, and docs table
• 14 guides in docs/: getting-started, configuration, conversations, queries, permissions, hooks, mcp, events, messages, sessions, client, errors, logging, architecture
• CLAUDE.md updated with docs table and new conventions
• .claude/rules/conventions.md updated with Stripe-style config, DSL builder, and Data.define prepend patterns

Bug fix

• SessionPaths.realpath — encode ASCII-8BIT paths to UTF-8 before unicode_normalize (fixes Encoding::CompatibilityError when session cwd comes from JSONL)

Tests

• 76 new unit tests across 5 new test files (Configuration, PermissionPolicy, HookRegistry, Message module, global defaults wiring)
• 3 new integration tests (ask lifecycle, PermissionPolicy via CLI, chat + Session resource)
• 1 new smoke test (ask via Ollama)
• All 1,221 unit tests pass, 0 rubocop offenses, RBS valid